#%RAML 0.8
---
title: system-agent
version: "1.1.x"
baseUri: "http://localhost:48090/api"
protocols: [ HTTP ]

documentation:
  - title: Welcome
    content: |
      Welcome to the System Management Agent Microservice API Documentation.

#TODO - someday specify the config and metric is a really a set of config/value pairs with categories
schemas:
    -
        config: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Service configuration","title":"config","properties":{"Service":{"type":"string","required":false,"title":"Service"},"Config":{"type":"string","required":false,"title":"Config"}}}'
    -
        metric: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Service metrics","title":"metric","properties":{"Service":{"type":"string","required":false,"title":"Service"},"Metrics":{"type":"string","required":false,"title":"Metrics"}}}'
    -
        operation: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"Service operation","title":"operation","properties":{"action":{"type":"string","required":false,"title":"Action"}, "services": {"type": "array","items": { "type": "string" },"uniqueItems": true}}}'

/v1/operation:
    displayName: Service Operation
    description: example - http://localhost:48090/api/v1/operation
    post:
        description: Issue a start, stop or restart action to the specified services.  HTTP 500 for unknown or unanticipated issues.
        displayName: service operation
        body:
            application/json:
                schema: operation
                example: '{"action":"stop","services":["edgex-support-notifications","edgex-core-data"]}'
        responses:
            "500":
                description: for unknown or unanticipated issues.
/v1/config/{services}:
    displayName: Service Configuration (by service names comma delimited)
    description: example - http://localhost:48090/api/v1/config/edgex-support-notifications,edgex-core-data
    uriParameters:
        services:
            displayName: service names
            description: EdgeX micro service names (the unique name of each service comma delimited)
            type: string
            required: true
            repeat: false
    get:
        description: "Fetch the configuration of the specified EdgeX services by their unique names - returning null if none is found for the service. HTTP 500 for unknown or unanticipated issues"
        displayName: get configuration for each of the names EdgeX services
        responses:
            "200":
                description: an array of config
                body:
                    application/json:
                        schema: config
                        example: '{"Service":"edgex-support-notifications","Config":{"Clients":{"Logging":{"Host":"localhost","Port":48061,"Protocol":"http"}},"Databases":{"Primary":{"Host":"localhost","Name":"notifications","Password":"","Port":27017,"Timeout":5000,"Type":"mongodb","Username":""}},"Logging":{"EnableRemote":false,"File":"./logs/edgex-support-notifications.log"},"Registry":{"Host":"localhost","Port":8500,"Type":"consul"},"ResendLimit":2,"Service":{"BootTimeout":30000,"CheckInterval":"10s","ClientMonitor":15000,"Host":"localhost","Port":48060,"Protocol":"http","MaxResultCount":1000,"StartupMsg":"This is the Support Notifications Microservice","Timeout":5000},"Smtp":{"Host":"smtp.gmail.com","Password":"mypassword","Port":587,"Sender":"jdoe@gmail.com","Subject":"EdgeX Notification"}}}'
            "500":
                description: for unknown or unanticipated issues.
/v1/metrics/{services}:
    displayName: Service Metrics (by service names comma delimited)
    description: example - http://localhost:48090/api/v1/metrics/edgex-support-notifications,edgex-core-data
    uriParameters:
        services:
            displayName: service names
            description: EdgeX micro service names (the unique name of each service comma delimited)
            type: string
            required: true
            repeat: false
    get:
        description: "Fetch the operating performance metrics of the specified EdgeX services by their unique names - returning null if none is found for the service. HTTP 500 for unknown or unanticipated issues"
        displayName: get metrics for each of the names EdgeX services
        responses:
            "200":
                description: an array of metrics
                body:
                    application/json:
                        schema: metric
                        example: '{"Service":"edgex-support-notifications","Metrics":{"Alloc":2128944,"Frees":5911,"LiveObjects":31630,"Mallocs":37541,"Sys":7211256,"TotalAlloc":2128944}}'
            "500":
                description: for unknown or unanticipated issues.
/v1/ping:
    displayName: Ping Resource
    description: example - http://localhost:48090/api/v1/ping
    get:
        description: Test service providing an indication that the service is available.
        displayName: service up check
        responses:
            "200":
                description: return value of "pong"
            "503":
                description: for unknown or unanticipated issues
/version:
    displayName: Edgex API Version
    description: Example - http://localhost:48090/api/version
    get:
        description: Get the API version
        responses:
            "200":
                description: The service's API version as JSON document
                body:
                  application/json:
                    example:  '{"version":"1.1.0"}'
